一、应用场景
用户身份认证是提供给C端用户认证自己房产的功能。用户在登录至App后，可以提交自己的身份证件信息。物业人员可以查看并审核用户提交的身份证件信息。在审核通过后，用户即可查看和管理自己房产的设备和场景信息。
用户通过App提交个人身份证件信息。
物业人员审核业主提交的个人身份证件信息。
二、功能说明
物联云平台提供三种业主认证方式，通过身份证件认证为其中一种。企业需要将住户信息添加至平台中。可通过【项目管理->住户管理】中进行手动添加，也可通过主数据同步的方式进行添加。添加完成住户信息后，由用户通过App提交身份证件信息。物业人员可前往【项目管理->身份认证】中进行审核。确认审核通过后，平台会依据手机号，将用户信息和住户信息进行绑定。用户即可在App中使用住户已关联房产的功能。
三、前提条件
1.用户提交身份认证前，需要先在管理台添加对应的住户。
四、关键流程
4.1 C端用户身份证件申请管理
流程说明：
- 首先，C端APP用户登录到物联网中台，获取到物联网中台的调用凭证以及刷新凭证。
- 其次，C端APP用户向物联网中台发起 上传用户身份证件 请求，物联网中台接收到请求后存储证件数据，返回用户身份证件标识。
- 再次，C端APP用户填写用户身份认证申请信息**(包括用户身份证件标识)**后，向物联网中台发起 提交用户身份认证申请 请求，物联网中台接收到请求经过一系列业务逻辑校验后进行持久化，返回认证申请标识。
- 最后，C端APP用户可以通过向物联网中台发起 获取用户身份认证申请列表 或者 获取用户身份认证申请 请求获得认证申请详情，提取认证申请中的用户身份认证证件标识，向物联网中台发起 获取用户身份证件 请求得到证件base64数据从而渲染用户身份证件。
4.2 B端用户身份证件申请管理
流程说明：
- 首先，B端成员登录到物联网中台，获取到物联网中台的调用凭证以及刷新凭证。
- 其次，B端成员向物联网中台发起 获取用户身份认证申请列表 请求 ，物联网中台接收到请求经过系列查询，返回企业下的用户身份认证申请列表。
- 再次，B端成员点击某个用户身份认证申请向物联网中台发起 获取用户身份证件 请求得到证件base64数据从而渲染用户身份证件，进而展示出某个用户身份认证的全部信息。
- 最后，B端成员校对用户身份认证申请后向物联网中台发起 审核用户身份认证申请 请求，物联网中台接收到请求后将申请状态进行变更，从而完成用户身份认证的申请。
五、API列表
5.1 用户身份认证
5.1.1 上传用户身份证件
接口描述
C端用户上传身份证件得到身份证件的唯一标识，用于关联相关认证（如住户房产）；上传的证件会使用用户隐私码配合AES加密算法进行加密得到字节流，将字节流上传到云存储厂商；该接口非Restful接口，请求报文为二进制文件字节流，文件大小需控制在5M内
请求方式
POST
请求地址
/v2/users/certificate-file?extend=xxxx
路径参数
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| extend | true | String | 1.格式为Base64(JSON字符串) 2.JSON字符串只允许一个层级，会当做拓展信息，JSON字符串必须包含 3.data_type 数据格式(data_type)，目前只支持图片格式，默认为jpeg，枚举如下: png/jpg/jpeg/bmp/gif/svg { “data_type”:”png” } |
请求头
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| Access-Token | true | String | 调用凭证 企业用户 |
| Content-Type | true | String | application/json |
请求参数
| 名称 | 位置 | 必填 | 类型 | 备注 |
|---|---|---|---|---|
| extend | query | true | String | 拓展属性 1.格式为Base64(JSON字符串) 2.JSON字符串只允许一个层级，会当做拓展信息，JSON字符串必须包含 3.data_type 数据格式(data_type)，目前只支持图片格式，默认为jpeg，枚举如下: png/jpg/jpeg/bmp/gif/svg { “data_type”:”png” } |
| — | body | —- | byte[] | 二进制字节流 |
请求示例：
二进制字节流返回参数说明
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| id | true | String | 用户身份证件标识 |
返回示例：
{
"id":"56156sdf156ef5dff"
}错误码：
| 错误码 | 描述 |
|---|---|
| 4001001 | 请求数据字段验证不通过 |
| 4001002 | 请求数据必须字段不可为空 |
| 4031001 | 调用凭证权限被禁止访问 |
| 4031003 | 无效的调用凭证 |
| 4031002 | 需要调用凭证 |
| 4041001 | 接口不存在 |
| 5031001 | 系统错误 |
| 4031024 | 权限不足 |
| 4041011 | 用户不存在 |
5.1.2 获取用户身份证件
接口描述
C端用户上传身份证件得到身份证件的唯一标识后，根据标识查询用户身份证件，用户页面展示；返回数据为文件内容的base64格式值；从云厂商获取得到数据，使用AES解密算法以用户隐私码解密，再以base64加密返回
请求方式
GET
请求地址
/v2/users/certificate-file/{id}
请求头
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| Access-Token | true | String | 调用凭证 企业用户 |
| Content-Type | true | String | application/json |
请求参数
| 名称 | 位置 | 必填 | 类型 | 备注 |
|---|---|---|---|---|
| id | path | true | String | 身份证件标识 |
请求示例：
{
}返回参数说明
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| data | true | String | 证件的base64编码数据 |
| extend | true | Object | 证件拓展属性 |
| extend.data_type | true | String | 数据格式，目前只支持图片格式，默认为jpeg，枚举如下: png/jpg/jpeg/bmp/gif/svg |
返回示例：
{
"data": "dsfaf54dsf51f5sdfds",
"extend": {
"data_type": "jpeg"
}
}错误码：
| 错误码 | 描述 |
|---|---|
| 4001001 | 请求数据字段验证不通过 |
| 4001002 | 请求数据必须字段不可为空 |
| 4031001 | 调用凭证权限被禁止访问 |
| 4031003 | 无效的调用凭证 |
| 4031002 | 需要调用凭证 |
| 4041001 | 接口不存在 |
| 5031001 | 系统错误 |
| 4031024 | 权限不足 |
| 4041098 | 用户身份证件不存在 |
5.1.3 提交用户身份认证申请
接口描述
C端用户为了通过身份认证，需要向平台提交证明自身身份的证件申请，并由相关人员进行审核；用户同一时间同一个类型证件只能提交一次申请
请求方式
POST
请求地址
/v2/users/certificate
请求头
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| Access-Token | true | String | 调用凭证 企业用户 |
| Content-Type | true | String | application/json |
请求参数
| 名称 | 位置 | 必填 | 类型 | 备注 |
|---|---|---|---|---|
| certificate_type | body | true | Int | 证件类型，枚举类型，目前只支持身份证 1: 身份证 2: 护照 3: 军官证 4: 港澳通行证 |
| certificate_id | body | true | String | 证件号码，根据类型不同有不同限制 |
| user_name | body | true | String | 证件用户名称 |
| phone | body | true | String | 证件用户手机号码 |
| config | body | true | Object | 申请配置, 依据certificate_type不同而不同 |
| config.id_card_front_id | body | false | String | 身份证正面图片标识，当certificate_type为1时必填 |
| config.id_card_back_id | body | false | String | 身份证反面图片标识，当certificate_type为1时必填 |
| config.certificate_file_ids | body | false | Array | 证件文件标识列表(文件ID)，主要用于type为2/3/4 |
请求示例：
{
"certificate_type": 1,
"certificate_id": "4418258963466456624",
"user_name": "李清华",
"phone": "13838383388",
"config": {
"id_card_front_id": "44182589634661151sdfsdf6624",
"id_card_back_id": "44182589634sdfsfsfdsfsd24",
"certificate_file_ids": ["44182589634661151sdfsdf6624"]
}
}返回参数说明
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| id | true | String | 申请记录标识 |
| user_id | true | Int | 申请用户标识 |
| status | true | Int | 认证审核状态，枚举 1: 待审核 2: 通过 3: 拒绝 |
| approval_remarks | false | String | 审批意见 |
| create_time | true | String | 申请认证记录提交时间 |
| processed_time | false | String | 申请认证记录处理时间 |
| certificate_type | true | Int | 证件类型，枚举类型，目前只支持身份证 1: 身份证 2: 护照 3: 军官证 4: 港澳通行证 |
| certificate_id | true | String | 证件号码，根据类型不同有不同限制 |
| user_name | true | String | 申请认证记录证件用户名称 |
| phone | true | String | 申请认证记录用户手机 |
| config | true | Object | 申请认证记录配置, 依据certificate_type不同而不同 |
| config.id_card_front_id | false | String | 身份证正面图片标识，当certificate_type为1时必填 |
| config.id_card_back_id | false | String | 身份证反面图片标识，当certificate_type为1时必填 |
| config.certificate_file_ids | false | Array | 证件文件标识列表(文件ID)，主要用于type为2/3/4 |
返回示例：
{
"id": "1s32ffffwe23rf5521dsf",
"user_id": 45623226,
"certificate_type": 1,
"certificate_id": "4456541563164654651",
"user_name": "李清华",
"status": 2,
"approval_remarks": "同意",
"create_time": "2019-12-16T16:00:00.000Z",
"processed_time": "2019-12-16T16:00:00.000Z",
"phone": "13838383388",
"config": {
"id_card_front_id": "44182589634661151sdfsdf6624",
"id_card_back_id": "44182589634sdfsfsfdsfsd24",
"certificate_file_ids": ["44182589634661151sdfsdf6624"]
}
}错误码：
| 错误码 | 描述 |
|---|---|
| 4001001 | 请求数据字段验证不通过 |
| 4001002 | 请求数据必须字段不可为空 |
| 4031001 | 调用凭证权限被禁止访问 |
| 4031003 | 无效的调用凭证 |
| 4031002 | 需要调用凭证 |
| 4041001 | 接口不存在 |
| 5031001 | 系统错误 |
| 4031024 | 权限不足 |
| 4041098 | 用户身份证件不存在 |
| 4001370 | 用户证件类型未知 |
| 4001380 | 用户认证已存在 |
5.1.4 审核用户身份认证申请
接口描述
企业成员针对用户提交的用户身份认证申请进行审核，审核结果将通过消息队列通知给产品使用者．认证申请必须处于待审核状态；审核选择只能是通过或者拒绝
请求方式
PUT
请求地址
/v2/users/certificates/{id}/audit
请求头
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| Access-Token | true | String | 调用凭证 企业用户 |
| Content-Type | true | String | application/json |
请求参数
| 名称 | 位置 | 必填 | 类型 | 备注 |
|---|---|---|---|---|
| id | path | true | String | 身份认证申请标识 |
| status | body | true | String | 认证审核状态，枚举类型 2: 通过 3: 拒绝 |
| approval_remarks | body | false | String | 审批意见 |
请求示例：
{
"status":2,
"approval_remarks": "同意申请"
}返回参数说明
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| 无 | 无 | 无 | 无 |
返回示例：
{
}错误码：
| 错误码 | 描述 |
|---|---|
| 4001001 | 请求数据字段验证不通过 |
| 4001002 | 请求数据必须字段不可为空 |
| 4031001 | 调用凭证权限被禁止访问 |
| 4031003 | 无效的调用凭证 |
| 4031002 | 需要调用凭证 |
| 4041001 | 接口不存在 |
| 5031001 | 系统错误 |
| 4031024 | 权限不足 |
| 4041098 | 用户身份证件不存在 |
| 4001372 | 认证申请不处于待审核状态 |
| 4001373 | 用户审核状态不支持 |
| 4001380 | 用户认证已存在 |
5.1.5 获取用户身份认证申请
接口描述
C端用户或者企业成员根据标识查询查询用户身份认证申请记录，用户前端查看展示
请求方式
GET
请求地址
/v2/users/certificates/{id}
请求头
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| Access-Token | true | String | 调用凭证 企业用户 企业成员 |
| Content-Type | true | String | application/json |
请求参数
| 名称 | 位置 | 必填 | 类型 | 备注 |
|---|---|---|---|---|
| id | path | true | String | 身份认证申请标识 |
请求示例：
{
}返回参数说明
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| id | true | String | 申请记录标识 |
| user_id | true | Int | 申请用户标识 |
| status | true | Int | 认证审核状态，枚举 1: 待审核 2: 通过 3: 拒绝 |
| approval_remarks | false | String | 审批意见 |
| create_time | true | String | 申请认证记录提交时间 |
| processed_time | false | String | 申请认证记录处理时间 |
| certificate_type | true | Int | 证件类型，枚举类型，目前只支持身份证 1: 身份证 2: 护照 3: 军官证 4: 港澳通行证 |
| certificate_id | true | String | 证件号码，根据类型不同有不同限制 |
| user_name | true | String | 申请认证记录证件用户名称 |
| phone | true | String | 申请认证记录用户手机 |
| config | true | Object | 申请认证记录配置, 依据certificate_type不同而不同 |
| config.id_card_front_id | false | String | 身份证正面图片标识，当certificate_type为1时必填 |
| config.id_card_back_id | false | String | 身份证反面图片标识，当certificate_type为1时必填 |
| config.certificate_file_ids | false | Array | 证件文件标识列表(文件ID)，主要用于type为2/3/4 |
返回示例：
{
"id": "1s32ffffwe23rf5521dsf",
"user_id": 45623226,
"certificate_type": 1,
"certificate_id": "4456541563164654651",
"user_name": "李清华",
"status": 2,
"approval_remarks": "同意",
"create_time": "2019-12-16T16:00:00.000Z",
"processed_time": "2019-12-16T16:00:00.000Z",
"phone": "13838383388",
"config": {
"id_card_front_id": "44182589634661151sdfsdf6624",
"id_card_back_id": "44182589634sdfsfsfdsfsd24",
"certificate_file_ids": ["44182589634661151sdfsdf6624"]
}
}错误码：
| 错误码 | 描述 |
|---|---|
| 4001001 | 请求数据字段验证不通过 |
| 4001002 | 请求数据必须字段不可为空 |
| 4031001 | 调用凭证权限被禁止访问 |
| 4031003 | 无效的调用凭证 |
| 4031002 | 需要调用凭证 |
| 4041001 | 接口不存在 |
| 5031001 | 系统错误 |
| 4031024 | 权限不足 |
| 4041098 | 用户身份证件不存在 |
| 4001370 | 用户证件类型未知 |
| 4001380 | 用户认证已存在 |
5.1.6 获取用户身份认证申请列表
接口描述
C端用户或者企业成员查询用户身份认证申请记录列表，用户APP或者企业管理台用于查看展示
请求方式
POST
请求地址
/v2/users/certificates
请求头
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| Access-Token | true | String | 调用凭证 企业用户 企业成员 |
| Content-Type | true | String | application/json |
请求参数
| 名称 | 位置 | 必填 | 类型 | 备注 |
|---|---|---|---|---|
| offset | body | false | Int | 偏移量 |
| limit | body | false | Int | 查询量 |
| sort | body | false | Object | 排序字段 |
| query | body | false | Object | 查询条件，支持操作符有 $eq：等于 $gt：大于 $lt：小于 $gte：大等于 $lte：小等于 $ne：不等于 $nin：不包含，用于数组 $in：包含，用于数组 $like：模糊匹配，用于字符串 $all：全都在，用于数组 |
请求示例：
{
"offset": 0,
"limit": 10,
"sort": {
"name": "desc"
},
"query": {
"id": {
"$eq": "123sdffwd1s21fs2d3g"
}
}
}返回参数说明
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| count | true | String | 审申请记录总数 |
| list | true | String | 申请记录列表 |
| list.id | true | String | 申请记录标识 |
| list.user_id | true | Int | 申请用户标识 |
| list.status | true | Int | 认证审核状态，枚举 1: 待审核 2: 通过 3: 拒绝 |
| list.approval_remarks | false | String | 审批意见 |
| list.create_time | true | String | 申请认证记录提交时间 |
| list.processed_time | false | String | 申请认证记录处理时间 |
| list.certificate_type | true | Int | 证件类型，枚举类型，目前只支持身份证 1: 身份证 2: 护照 3: 军官证 4: 港澳通行证 |
| list.certificate_id | true | String | 证件号码，根据类型不同有不同限制 |
| list.user_name | true | String | 申请认证记录证件用户名称 |
| list.phone | true | String | 申请认证记录用户手机 |
| list.config | true | Object | 申请认证记录配置, 依据certificate_type不同而不同 |
| list.config.id_card_front_id | false | String | 身份证正面图片标识，当certificate_type为1时必填 |
| list.config.id_card_back_id | false | String | 身份证反面图片标识，当certificate_type为1时必填 |
| list.config.certificate_file_ids | false | Array | 证件文件标识列表(文件ID)，主要用于type为2/3/4 |
返回示例：
{
"count": 1,
"list": [{
"id": "1s32ffffwe23rf5521dsf",
"user_id": 45623226,
"certificate_type": 1,
"certificate_id": "4456541563164654651",
"user_name": "李清华",
"status": 2,
"approval_remarks": "同意",
"create_time": "2019-12-16T16:00:00.000Z",
"processed_time": "2019-12-16T16:00:00.000Z",
"phone": "13838383388",
"config": {
"id_card_front_id": "44182589634661151sdfsdf6624",
"id_card_back_id": "44182589634sdfsfsfdsfsd24",
"certificate_file_ids": ["44182589634661151sdfsdf6624"]
}
}]
}错误码：
| 错误码 | 描述 |
|---|---|
| 4001001 | 请求数据字段验证不通过 |
| 4001002 | 请求数据必须字段不可为空 |
| 4031001 | 调用凭证权限被禁止访问 |
| 4031003 | 无效的调用凭证 |
| 4031002 | 需要调用凭证 |
| 4041001 | 接口不存在 |
| 5031001 | 系统错误 |
| 4031024 | 权限不足 |
| 4041098 | 用户身份证件不存在 |
| 4001370 | 用户证件类型未知 |
